<?xml version="1.0" encoding="ascii"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
          "DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>robotide.publish</title>
  <link rel="stylesheet" href="epydoc.css" type="text/css" />
  <script type="text/javascript" src="epydoc.js"></script>
</head>

<body bgcolor="white" text="black" link="blue" vlink="#204080"
      alink="#204080">
<!-- ==================== NAVIGATION BAR ==================== -->
<table class="navbar" border="0" width="100%" cellpadding="0"
       bgcolor="#a0c0ff" cellspacing="0">
  <tr valign="middle">
  <!-- Home link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="robotide-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Tree link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Index link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Help link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Project homepage -->
      <th class="navbar" align="right" width="100%">
        <table border="0" cellpadding="0" cellspacing="0">
          <tr><th class="navbar" align="center"
            ><a class="navbar" target="_top" href="http://code.google.com/p/robotframework-ride">RIDE</a></th>
          </tr></table></th>
  </tr>
</table>
<table width="100%" cellpadding="0" cellspacing="0">
  <tr valign="top">
    <td width="100%">
      <span class="breadcrumbs">
        <a href="robotide-module.html">Package&nbsp;robotide</a> ::
        Package&nbsp;publish
      </span>
    </td>
    <td>
      <table cellpadding="0" cellspacing="0">
        <!-- hide/show private -->
      </table>
    </td>
  </tr>
</table>
<!-- ==================== PACKAGE DESCRIPTION ==================== -->
<h1 class="epydoc">Package publish</h1><p class="nomargin-top"><span class="codelink"><a href="robotide.publish-pysrc.html">source&nbsp;code</a></span></p>
<p>Message publishing and subscribing.</p>
<div class="rst-contents rst-local rst-topic" id="rst-contents">
<ul class="rst-simple">
<li><a class="rst-reference internal" href="#rst-introduction" id="rst-id1">Introduction</a></li>
<li><a class="rst-reference internal" href="#rst-subscribing" id="rst-id2">Subscribing</a><ul>
<li><a class="rst-reference internal" href="#rst-message-topics" id="rst-id3">Message topics</a></li>
<li><a class="rst-reference internal" href="#rst-listeners" id="rst-id4">Listeners</a></li>
<li><a class="rst-reference internal" href="#rst-unsubscribing" id="rst-id5">Unsubscribing</a></li>
</ul>
</li>
<li><a class="rst-reference internal" href="#rst-publishing-messages" id="rst-id6">Publishing messages</a><ul>
<li><a class="rst-reference internal" href="#rst-custom-messages" id="rst-id7">Custom messages</a></li>
</ul>
</li>
</ul>
</div>
<div class="rst-section" id="rst-introduction">
<h1 class="heading"><a class="rst-toc-backref" href="#rst-id1">Introduction</a></h1>
<p>RIDE uses messages for communication when something of interest happens, for
example a suite is loaded or item is selected in the tree. This module provides
means both for subscribing to listen to those messages and for sending them.
Messages are used for communication between the different components of the
core application, but their main usage is notifying plugins about various events.
Plugins can also send messages themselves, and also create custom messages, if
they have a need.</p>
</div>
<div class="rst-section" id="rst-subscribing">
<h1 class="heading"><a class="rst-toc-backref" href="#rst-id2">Subscribing</a></h1>
<p>The core application uses the global <a href="robotide.publish-module.html#PUBLISHER" class="link">PUBLISHER</a> object (an instance of the
<a href="robotide.publish.publisher.Publisher-class.html" class="link">Publisher</a> class) for subscribing to and unsubscribing from the messages.
Plugins should use the helper methods of the <a href="robotide.pluginapi.plugin.Plugin-class.html" class="link">Plugin</a> class instead of using
the <a href="robotide.publish-module.html#PUBLISHER" class="link">PUBLISHER</a> directly.</p>
<div class="rst-section" id="rst-message-topics">
<h2 class="heading"><a class="rst-toc-backref" href="#rst-id3">Message topics</a></h2>
<p>Regardless the method, subscribing to messages requires a message topic.
Topics can be specified using the actual message classes in
<a href="robotide.publish.messages-module.html" class="link">robotide.publish.messages</a> module or with their dot separated topic strings.
It is, for example, equivalent to use the <a href="robotide.publish.messages.RideTreeSelection-class.html" class="link">RideTreeSelection</a> class and a
string <tt class="rst-docutils literal">ride.tree.selection</tt>. Topic strings can normally, but not always, be
mapped directly to the class names.</p>
<p>The topic strings represents a hierarchy where the dots separate the hierarchy
levels. All messages with a topic at or below the given level will match the
subscribed topic. For example, subscribing to the <tt class="rst-docutils literal">ride.notebook</tt> topic means
that <a href="robotide.publish.messages.RideNotebookTabChanged-class.html" class="link">RideNotebookTabChanged</a> or any other message with a topic starting with
<tt class="rst-docutils literal">ride.notebook</tt> will match.</p>
</div>
<div class="rst-section" id="rst-listeners">
<h2 class="heading"><a class="rst-toc-backref" href="#rst-id4">Listeners</a></h2>
<p>Another thing needed when subscribing is a listener, which must be a callable
accepting one argument. When the corresponding message is published, the listener
will be called with an instance of the message class as an argument. That instance
contains the topic and possibly some additional information in its attributes.</p>
<p>The following example demonstrates how a plugin can subscribe to an event.
In this example the <tt class="rst-docutils literal">OnTreeSelection</tt> method is the listener and the
<tt class="rst-docutils literal">message</tt> it receives is an instance of the <a href="robotide.publish.messages.RideTreeSelection-class.html" class="link">RideTreeSelection</a> class.</p>
<pre class="rst-literal-block">
from robotide.pluginapi import Plugin, RideTreeSelection

class MyFancyPlugin(Plugin):
   def activate(self):
       self.subscribe(self.OnTreeSelection, RideTreeSelection)

   def OnTreeSelection(self, message):
       print message.topic, message.node
</pre>
</div>
<div class="rst-section" id="rst-unsubscribing">
<h2 class="heading"><a class="rst-toc-backref" href="#rst-id5">Unsubscribing</a></h2>
<p>Unsubscribing from a single message requires passing the same topic and listener
to the unsubscribe method that were used for subscribing. Additionally both
the <a href="robotide.publish-module.html#PUBLISHER" class="link">PUBLISHER</a> object and the <a href="robotide.pluginapi.plugin.Plugin-class.html" class="link">Plugin</a> class provide a method for unsubscribing
all listeners registered by someone.</p>
</div>
</div>
<div class="rst-section" id="rst-publishing-messages">
<h1 class="heading"><a class="rst-toc-backref" href="#rst-id6">Publishing messages</a></h1>
<p>Both the core application and plugins can publish messages using message
classes in the <a href="robotide.publish.messages-module.html" class="link">publish.messages</a> module directly. Sending a message is as easy
as creating an instance of the class and calling its <tt class="rst-docutils literal">publish</tt> method. What
parameters are need when the instance is created depends on the message.</p>
<div class="rst-section" id="rst-custom-messages">
<h2 class="heading"><a class="rst-toc-backref" href="#rst-id7">Custom messages</a></h2>
<p>Most of the messages in the <a href="robotide.publish.messages-module.html" class="link">publish.messages</a> module are to be sent only by
the core application. If plugins need their own messages, for example for
communication between different plugins, they can easily create custom messages
by extending the <a href="robotide.publish.messages.RideMessage-class.html" class="link">RideMessage</a> base class:</p>
<pre class="rst-literal-block">
from robotide.pluginapi import Plugin, RideMessage

class FancyImportantMessage(RideMessage):
    data = ['importance']

class MyFancyPlugin(Plugin):
    def important_action(self):
        # some code ...
        MyImportantMessage(importance='HIGH').publish()
</pre>
<p>Plugins interested about this message can subscribe to it using either
the class <tt class="rst-docutils literal">FancyImportantMessage</tt> or its automatically generated title
<tt class="rst-docutils literal">fancy.important</tt>. Notice also that all the messages are exposed also through
the <a href="robotide.pluginapi-module.html" class="link">robotide.pluginapi</a> module and plugins should import them there.</p>
</div>
</div>

<!-- ==================== SUBMODULES ==================== -->
<a name="section-Submodules"></a>
<table class="summary" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td align="left" colspan="2" class="table-header">
    <span class="table-header">Submodules</span></td>
</tr>
  <tr><td class="summary">
  <ul class="nomargin">
    <li> <strong class="uidlink"><a href="robotide.publish.messages-module.html">robotide.publish.messages</a></strong>    </li>
    <li> <strong class="uidlink"><a href="robotide.publish.messagetype-module.html">robotide.publish.messagetype</a></strong>    </li>
    <li> <strong class="uidlink"><a href="robotide.publish.publisher-module.html">robotide.publish.publisher</a></strong>    </li>
  </ul></td></tr>
</table>

<br />
<!-- ==================== VARIABLES ==================== -->
<a name="section-Variables"></a>
<table class="summary" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td align="left" colspan="2" class="table-header">
    <span class="table-header">Variables</span></td>
</tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a href="robotide.publish-module.html#PUBLISHER" class="summary-name">PUBLISHER</a> = <code title="Publisher()">Publisher()</code><br />
      Global <a href="robotide.publish.publisher.Publisher-class.html" class="link">Publisher</a> instance for subscribing to and unsubscribing from messages.
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a href="robotide.publish-module.html#__package__" class="summary-name">__package__</a> = <code title="'robotide.publish'"><code class="variable-quote">'</code><code class="variable-string">robotide.publish</code><code class="variable-quote">'</code></code>
    </td>
  </tr>
</table>
<p class="indent-wrapped-lines"><b>Imports:</b>
  <a href="robotide.publish.publisher.Publisher-class.html" title="robotide.publish.publisher.Publisher">Publisher</a>,
  <a href="robotide.publish.messages.RideChangeFormat-class.html" title="robotide.publish.messages.RideChangeFormat">RideChangeFormat</a>,
  <a href="robotide.publish.messages.RideClosing-class.html" title="robotide.publish.messages.RideClosing">RideClosing</a>,
  <a href="robotide.publish.messages.RideDataChangedToDirty-class.html" title="robotide.publish.messages.RideDataChangedToDirty">RideDataChangedToDirty</a>,
  <a href="robotide.publish.messages.RideDataDirtyCleared-class.html" title="robotide.publish.messages.RideDataDirtyCleared">RideDataDirtyCleared</a>,
  <a href="robotide.publish.messages.RideDataFileRemoved-class.html" title="robotide.publish.messages.RideDataFileRemoved">RideDataFileRemoved</a>,
  <a href="robotide.publish.messages.RideGridCellChanged-class.html" title="robotide.publish.messages.RideGridCellChanged">RideGridCellChanged</a>,
  <a href="robotide.publish.messages.RideImportSetting-class.html" title="robotide.publish.messages.RideImportSetting">RideImportSetting</a>,
  <a href="robotide.publish.messages.RideImportSettingAdded-class.html" title="robotide.publish.messages.RideImportSettingAdded">RideImportSettingAdded</a>,
  <a href="robotide.publish.messages.RideImportSettingChanged-class.html" title="robotide.publish.messages.RideImportSettingChanged">RideImportSettingChanged</a>,
  <a href="robotide.publish.messages.RideImportSettingRemoved-class.html" title="robotide.publish.messages.RideImportSettingRemoved">RideImportSettingRemoved</a>,
  <a href="robotide.publish.messages.RideInitFileRemoved-class.html" title="robotide.publish.messages.RideInitFileRemoved">RideInitFileRemoved</a>,
  <a href="robotide.publish.messages.RideItem-class.html" title="robotide.publish.messages.RideItem">RideItem</a>,
  <a href="robotide.publish.messages.RideItemNameChanged-class.html" title="robotide.publish.messages.RideItemNameChanged">RideItemNameChanged</a>,
  <a href="robotide.publish.messages.RideItemSettingsChanged-class.html" title="robotide.publish.messages.RideItemSettingsChanged">RideItemSettingsChanged</a>,
  <a href="robotide.publish.messages.RideItemStepsChanged-class.html" title="robotide.publish.messages.RideItemStepsChanged">RideItemStepsChanged</a>,
  <a href="robotide.publish.messages.RideLog-class.html" title="robotide.publish.messages.RideLog">RideLog</a>,
  <a href="robotide.publish.messages.RideLogException-class.html" title="robotide.publish.messages.RideLogException">RideLogException</a>,
  <a href="robotide.publish.messages.RideLogMessage-class.html" title="robotide.publish.messages.RideLogMessage">RideLogMessage</a>,
  <a href="robotide.publish.messages.RideMessage-class.html" title="robotide.publish.messages.RideMessage">RideMessage</a>,
  <a href="robotide.publish.messages.RideNewProject-class.html" title="robotide.publish.messages.RideNewProject">RideNewProject</a>,
  <a href="robotide.publish.messages.RideNotebookTabChanged-class.html" title="robotide.publish.messages.RideNotebookTabChanged">RideNotebookTabChanged</a>,
  <a href="robotide.publish.messages.RideNotebookTabChanging-class.html" title="robotide.publish.messages.RideNotebookTabChanging">RideNotebookTabChanging</a>,
  <a href="robotide.publish.messages.RideOpenResource-class.html" title="robotide.publish.messages.RideOpenResource">RideOpenResource</a>,
  <a href="robotide.publish.messages.RideOpenSuite-class.html" title="robotide.publish.messages.RideOpenSuite">RideOpenSuite</a>,
  <a href="robotide.publish.messages.RideSaveAll-class.html" title="robotide.publish.messages.RideSaveAll">RideSaveAll</a>,
  <a href="robotide.publish.messages.RideSaved-class.html" title="robotide.publish.messages.RideSaved">RideSaved</a>,
  <a href="robotide.publish.messages.RideSaving-class.html" title="robotide.publish.messages.RideSaving">RideSaving</a>,
  <a href="robotide.publish.messages.RideSelectResource-class.html" title="robotide.publish.messages.RideSelectResource">RideSelectResource</a>,
  <a href="robotide.publish.messages.RideSettingsChanged-class.html" title="robotide.publish.messages.RideSettingsChanged">RideSettingsChanged</a>,
  <a href="robotide.publish.messages.RideSuiteAdded-class.html" title="robotide.publish.messages.RideSuiteAdded">RideSuiteAdded</a>,
  <a href="robotide.publish.messages.RideTestCaseAdded-class.html" onclick="show_private();" title="robotide.publish.messages.RideTestCaseAdded">RideTestCaseAdded</a>,
  <a href="robotide.publish.messages.RideTestCaseRemoved-class.html" title="robotide.publish.messages.RideTestCaseRemoved">RideTestCaseRemoved</a>,
  <a href="robotide.publish.messages.RideTreeSelection-class.html" title="robotide.publish.messages.RideTreeSelection">RideTreeSelection</a>,
  <a href="robotide.publish.messages.RideUserKeyword-class.html" title="robotide.publish.messages.RideUserKeyword">RideUserKeyword</a>,
  <a href="robotide.publish.messages.RideUserKeywordAdded-class.html" title="robotide.publish.messages.RideUserKeywordAdded">RideUserKeywordAdded</a>,
  <a href="robotide.publish.messages.RideUserKeywordRemoved-class.html" title="robotide.publish.messages.RideUserKeywordRemoved">RideUserKeywordRemoved</a>,
  <a href="robotide.publish.messages.RideVariableAdded-class.html" title="robotide.publish.messages.RideVariableAdded">RideVariableAdded</a>,
  <a href="robotide.publish.messages.RideVariableMovedDown-class.html" title="robotide.publish.messages.RideVariableMovedDown">RideVariableMovedDown</a>,
  <a href="robotide.publish.messages.RideVariableMovedUp-class.html" title="robotide.publish.messages.RideVariableMovedUp">RideVariableMovedUp</a>,
  <a href="robotide.publish.messages.RideVariableRemoved-class.html" title="robotide.publish.messages.RideVariableRemoved">RideVariableRemoved</a>,
  <a href="robotide.publish.messages.RideVariableUpdated-class.html" title="robotide.publish.messages.RideVariableUpdated">RideVariableUpdated</a>,
  <a href="robotide.publish.messages-module.html" title="robotide.publish.messages">messages</a>,
  <a href="robotide.publish.messagetype-module.html" title="robotide.publish.messagetype">messagetype</a>,
  <a href="robotide.publish.publisher-module.html" title="robotide.publish.publisher">publisher</a>
</p><br />
<!-- ==================== VARIABLES DETAILS ==================== -->
<a name="section-VariablesDetails"></a>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td align="left" colspan="2" class="table-header">
    <span class="table-header">Variables Details</span></td>
</tr>
</table>
<a name="PUBLISHER"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <h3 class="epydoc">PUBLISHER</h3>
  Global <a href="robotide.publish.publisher.Publisher-class.html" class="link">Publisher</a> instance for subscribing to and unsubscribing from messages.
  <dl class="fields">
  </dl>
  <dl class="fields">
    <dt>Value:</dt>
      <dd><table><tr><td><pre class="variable">
Publisher()
</pre></td></tr></table>
</dd>
  </dl>
</td></tr></table>
</div>
<a name="__package__"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <h3 class="epydoc">__package__</h3>
  
  <dl class="fields">
  </dl>
  <dl class="fields">
    <dt>Value:</dt>
      <dd><table><tr><td><pre class="variable">
<code class="variable-quote">'</code><code class="variable-string">robotide.publish</code><code class="variable-quote">'</code>
</pre></td></tr></table>
</dd>
  </dl>
</td></tr></table>
</div>
<br />
<!-- ==================== NAVIGATION BAR ==================== -->
<table class="navbar" border="0" width="100%" cellpadding="0"
       bgcolor="#a0c0ff" cellspacing="0">
  <tr valign="middle">
  <!-- Home link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="robotide-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Tree link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Index link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Help link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Project homepage -->
      <th class="navbar" align="right" width="100%">
        <table border="0" cellpadding="0" cellspacing="0">
          <tr><th class="navbar" align="center"
            ><a class="navbar" target="_top" href="http://code.google.com/p/robotframework-ride">RIDE</a></th>
          </tr></table></th>
  </tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%%">
  <tr>
    <td align="left" class="footer">
    Generated by Epydoc 3.0.1 on Wed Apr 13 15:09:36 2011
    </td>
    <td align="right" class="footer">
      <a target="mainFrame" href="http://epydoc.sourceforge.net"
        >http://epydoc.sourceforge.net</a>
    </td>
  </tr>
</table>

<script type="text/javascript">
  <!--
  // Private objects are initially displayed (because if
  // javascript is turned off then we want them to be
  // visible); but by default, we want to hide them.  So hide
  // them unless we have a cookie that says to show them.
  checkCookie();
  // -->
</script>
</body>
</html>
